// 版权所有2009 Go作者。保留所有权利。
// 此源代码的使用受BSD样式
// 许可证的约束，该许可证可以在许可证文件中找到。

package xml

import (
	"bytes"
	"encoding"
	"errors"
	"fmt"
	"reflect"
	"strconv"
	"strings"
)

// 错误（rsc）：XML元素和数据结构之间的映射存在固有缺陷：
// XML元素是匿名
// 值的顺序相关集合，而数据结构是命名值的顺序无关集合
// 。
// 有关更适合数据结构的文本表示，请参阅json包。

// Unmarshal解析XML编码的数据，并将结果存储在
// v所指向的值中，该值必须是任意结构、
// 切片或字符串。不适合v的格式良好的数据被
// 丢弃。
// 
// 因为反汇编使用反射包，所以它只能将
// 分配给导出的（大写）字段。Unmarshal使用区分大小写的
// 比较将XML元素名与标记值和结构
// 字段名相匹配。
// 
// Unmarshal使用以下规则将XML元素映射到结构。
// 在规则中，字段的标记是指与结构字段标记中的
// 键“xml”相关联的值（参见上面的示例）。
// 
// *如果结构具有类型为[]字节或字符串且带有标记
// “、innerxml”的字段，Unmarshal会将嵌套在该字段中
// 元素内的原始XML累加。其余规则仍然适用。
// 
// *如果结构有一个名为XMLName且类型为Name的字段，
// Unmarshal会在该字段中记录元素名称。
// 
// *如果XMLName字段具有形式为
// “name”或“namespace URL name”的关联标记，则XML元素必须具有给定名称（以及可选的名称空间）的
// ，否则将解组
// 返回错误。
// 
// *如果XML元素具有一个属性，其名称与
// 结构域名称匹配，并带有一个包含“、attr”或
// 格式为“name，attr”的结构域标记中的显式名称的关联标记，则
// 解组会在该字段中记录属性值。
// 
// *如果XML元素有一个属性未被前一个
// 规则处理，并且该结构有一个字段，该字段带有一个包含
// “、any、attr”的关联标记，则Unmarshal会在第一个
// 此类字段中记录属性值。
// 
// *如果XML元素包含字符数据，则该数据将累积在第一个带有标记“chardata”的结构字段中。
// 结构字段的类型可能为[]字节或字符串。
// 如果没有这样的字段，字符数据将被丢弃。
// 
// *如果XML元素包含注释，它们将累积在
// 第一个带有标记“comment”的结构字段中。struct 
// 字段的类型可能为[]字节或字符串。如果没有这样的
// 字段，则放弃注释。
// 
// *如果XML元素包含一个子元素，其名称与
// 格式为“a”或“a>b>c”的标记的前缀匹配，unmarshal 
// 将进入XML结构，查找具有
// 给定名称的元素，并将最里面的元素映射到该结构
// 字段。以“>”开头的标记相当于以
// 开头、字段名后跟“>”的标记。
// 
// *如果XML元素包含一个子元素，其名称与
// 结构字段的XMLName标记匹配，而结构字段没有
// 根据前面的规则显式名称标记，则解组将
// 子元素映射到该结构字段。
// 
// *如果XML元素包含一个子元素，其名称与
// 字段匹配，且没有任何模式标志（“、attr”、“、chardata”等），则解组
// 将该子元素映射到该结构字段。
// 
// *如果XML元素包含未匹配上述规则中任何
// 的子元素，并且结构具有带标记“any”的字段，则
// 解组将子元素映射到该结构字段。
// 
// /*匿名结构字段的处理方式与其
// 值是外部结构的一部分。
// 
// *带“-”标记的结构字段永远不会被解组。
// 
// 如果Unmarshal遇到实现Unmarshaler 
// 接口的字段类型，Unmarshal将调用其UnmarshalXML方法从XML元素
// 生成值。否则，如果该值实现
// 编码。TextUnmarshaler，Unmarshal调用该值的UnmarshalText方法。
// 
// 通过保存字符串或
// /[]字节中该元素的字符数据的串联，将XML元素映射到字符串或[]字节。保存的[]字节从不为零。
// 
// 通过保存字符串或切片中的值，解组将属性值映射到字符串或[]字节。
// 
// 通过将属性
// 包括其名称保存在属性中，将属性值映射到属性。
// 
// Unmarshal通过
// 扩展切片的长度并将元素或属性
// 映射到新创建的值，将XML元素或属性值映射到切片。
// 
// Unmarshal通过
// 将XML元素或属性值映射到布尔值，并将其设置为字符串表示的布尔值。空格
// 被删除并忽略。
// 
// 解组将XML元素或属性值映射为整数或
// 浮点字段，方法是将字段设置为
// 以十进制解释字符串值的结果。没有检查
// 溢出。空白被删减并忽略。
// 
// Unmarshal通过记录元素
// Name将XML元素映射到名称。
// 
// Unmarshal通过将指针
// 设置为新分配的值，然后将元素映射到该值，将XML元素映射到指针。
// 
// 缺少的元素或空属性值将被解组为零值。
// 如果该字段是一个切片，则该字段将附加一个零值。否则，
// 字段将被设置为零值。
func Unmarshal(data []byte, v any) error {
	return NewDecoder(bytes.NewReader(data)).Decode(v)
}

// Decode的工作原理与Unmarshal类似，只是它读取解码器
// 流以找到起始元素。
func (d *Decoder) Decode(v any) error {
	return d.DecodeElement(v, nil)
}

// DecodeElement的工作原理类似于解组，不同的是它需要一个指向起始XML元素的指针来解码为v.
// 当客户机读取一些原始XML标记本身时，它很有用
// 但也希望延迟解组某些元素。
func (d *Decoder) DecodeElement(v any, start *StartElement) error {
	val := reflect.ValueOf(v)
	if val.Kind() != reflect.Pointer {
		return errors.New("non-pointer passed to Unmarshal")
	}
	return d.unmarshal(val.Elem(), start)
}

// 解组错误表示解组过程中的错误。
type UnmarshalError string

func (e UnmarshalError) Error() string { return string(e) }

// 解组器是由对象实现的接口，可以解组
// 对其自身的XML元素描述。
// 
// 解组XML解码单个XML元素
// 从给定的起始元素开始。
// 如果返回错误，则对解组的外部调用停止，
// 返回该错误。
// 解组XML必须只使用一个XML元素。
// 一种常见的实现策略是使用d.DecodeElement将一个单独的值解组为
// 一个布局与预期的XML 
// 匹配的值，然后将数据从
// 复制到接收器中。
// 另一种常用策略是使用d.Token一次处理一个Token。
// 解组XML不能使用d.RawToken。
type Unmarshaler interface {
	UnmarshalXML(d *Decoder, start StartElement) error
}

// 解组器是由对象实现的接口，可以解组
// 自身的XML属性描述。
// 
// UnmarshalXMLAttr解码单个XML属性。
// 如果返回错误，则对解组的外部调用将停止，
// 将返回该错误。
// UnmarshalXMLAttr仅用于字段标记中带有
// “attr”选项的结构字段。
type UnmarshalerAttr interface {
	UnmarshalXMLAttr(attr Attr) error
}

// receiverType返回要在表达式“%s.MethodName”中使用的接收器类型。
func receiverType(val any) string {
	t := reflect.TypeOf(val)
	if t.Name() != "" {
		return t.String()
	}
	return "(" + t.String() + ")"
}

// 解组界面将单个XML元素解组为val。
// 开始是元素的开始标记。
func (d *Decoder) unmarshalInterface(val Unmarshaler, start *StartElement) error {
	// 记录解码器必须在与开始对应的结束标记处停止。
	d.pushEOF()

	d.unmarshalDepth++
	err := val.UnmarshalXML(d, *start)
	d.unmarshalDepth--
	if err != nil {
		d.popEOF()
		return err
	}

	if !d.popEOF() {
		return fmt.Errorf("xml: %s.UnmarshalXML did not consume entire <%s> element", receiverType(val), start.Name.Local)
	}

	return nil
}

// unmarshalTextInterface将单个XML元素解组为val。
// 元素（但不是其子元素）中包含的字符数据
// 将传递给文本解组器。
func (d *Decoder) unmarshalTextInterface(val encoding.TextUnmarshaler) error {
	var buf []byte
	depth := 1
	for depth > 0 {
		t, err := d.Token()
		if err != nil {
			return err
		}
		switch t := t.(type) {
		case CharData:
			if depth == 1 {
				buf = append(buf, t...)
			}
		case StartElement:
			depth++
		case EndElement:
			depth--
		}
	}
	return val.UnmarshalText(buf)
}

// unmarshalatr将单个XML属性解组到val中。
func (d *Decoder) unmarshalAttr(val reflect.Value, attr Attr) error {
	if val.Kind() == reflect.Pointer {
		if val.IsNil() {
			val.Set(reflect.New(val.Type().Elem()))
		}
		val = val.Elem()
	}
	if val.CanInterface() && val.Type().Implements(unmarshalerAttrType) {
		// 这是一个带有非指针接收器的解组器，
		// 因此可能不正确，但我们会按要求执行。
		return val.Interface().(UnmarshalerAttr).UnmarshalXMLAttr(attr)
	}
	if val.CanAddr() {
		pv := val.Addr()
		if pv.CanInterface() && pv.Type().Implements(unmarshalerAttrType) {
			return pv.Interface().(UnmarshalerAttr).UnmarshalXMLAttr(attr)
		}
	}

	// 不是一个破译者；尝试编码。文本解压器。
	if val.CanInterface() && val.Type().Implements(textUnmarshalerType) {
		// 这是一个带有非指针接收器的解组器，
		// 所以这可能是错误的，但我们按照要求去做。
		return val.Interface().(encoding.TextUnmarshaler).UnmarshalText([]byte(attr.Value))
	}
	if val.CanAddr() {
		pv := val.Addr()
		if pv.CanInterface() && pv.Type().Implements(textUnmarshalerType) {
			return pv.Interface().(encoding.TextUnmarshaler).UnmarshalText([]byte(attr.Value))
		}
	}

	if val.Type().Kind() == reflect.Slice && val.Type().Elem().Kind() != reflect.Uint8 {
		// 元素值的切片。
		// 生长切片。
		n := val.Len()
		val.Set(reflect.Append(val, reflect.Zero(val.Type().Elem())))

		// 重复将元素读入切片。
		if err := d.unmarshalAttr(val.Index(n), attr); err != nil {
			val.SetLen(n)
			return err
		}
		return nil
	}

	if val.Type() == attrType {
		val.Set(reflect.ValueOf(attr))
		return nil
	}

	return copyValue(val, []byte(attr.Value))
}

var (
	attrType            = reflect.TypeOf(Attr{})
	unmarshalerType     = reflect.TypeOf((*Unmarshaler)(nil)).Elem()
	unmarshalerAttrType = reflect.TypeOf((*UnmarshalerAttr)(nil)).Elem()
	textUnmarshalerType = reflect.TypeOf((*encoding.TextUnmarshaler)(nil)).Elem()
)

// 将单个XML元素解压到val中。
func (d *Decoder) unmarshal(val reflect.Value, start *StartElement) error {
	// 如果需要，请查找start元素。
	if start == nil {
		for {
			tok, err := d.Token()
			if err != nil {
				return err
			}
			if t, ok := tok.(StartElement); ok {
				start = &t
				break
			}
		}
	}

	// 从接口加载值，但前提是结果是
	// 有效可寻址。
	if val.Kind() == reflect.Interface && !val.IsNil() {
		e := val.Elem()
		if e.Kind() == reflect.Pointer && !e.IsNil() {
			val = e
		}
	}

	if val.Kind() == reflect.Pointer {
		if val.IsNil() {
			val.Set(reflect.New(val.Type().Elem()))
		}
		val = val.Elem()
	}

	if val.CanInterface() && val.Type().Implements(unmarshalerType) {
		// 这是一个带有非指针接收器的解组器，
		// 所以这可能是错误的，但我们会按要求去做。
		return d.unmarshalInterface(val.Interface().(Unmarshaler), start)
	}

	if val.CanAddr() {
		pv := val.Addr()
		if pv.CanInterface() && pv.Type().Implements(unmarshalerType) {
			return d.unmarshalInterface(pv.Interface().(Unmarshaler), start)
		}
	}

	if val.CanInterface() && val.Type().Implements(textUnmarshalerType) {
		return d.unmarshalTextInterface(val.Interface().(encoding.TextUnmarshaler))
	}

	if val.CanAddr() {
		pv := val.Addr()
		if pv.CanInterface() && pv.Type().Implements(textUnmarshalerType) {
			return d.unmarshalTextInterface(pv.Interface().(encoding.TextUnmarshaler))
		}
	}

	var (
		data         []byte
		saveData     reflect.Value
		comment      []byte
		saveComment  reflect.Value
		saveXML      reflect.Value
		saveXMLIndex int
		saveXMLData  []byte
		saveAny      reflect.Value
		sv           reflect.Value
		tinfo        *typeInfo
		err          error
	)

	switch v := val; v.Kind() {
	default:
		return errors.New("unknown type " + v.Type().String())

	case reflect.Interface:
		// TODO:现在，只需忽略该字段即可。在不久的将来，如果不是空的话，我们可能会选择解封上面的start 
		// 元素。
		return d.Skip()

	case reflect.Slice:
		typ := v.Type()
		if typ.Elem().Kind() == reflect.Uint8 {
			// /[]字节
			saveData = v
			break
		}

		// 元素值的切片。
		// 生长切片。
		n := v.Len()
		v.Set(reflect.Append(val, reflect.Zero(v.Type().Elem())))

		// 重复将元素读入切片。
		if err := d.unmarshal(v.Index(n), start); err != nil {
			v.SetLen(n)
			return err
		}
		return nil

	case reflect.Bool, reflect.Float32, reflect.Float64, reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64, reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64, reflect.Uintptr, reflect.String:
		saveData = v

	case reflect.Struct:
		typ := v.Type()
		if typ == nameType {
			v.Set(reflect.ValueOf(start.Name))
			break
		}

		sv = v
		tinfo, err = getTypeInfo(typ)
		if err != nil {
			return err
		}

		// 验证并分配元素名称。
		if tinfo.xmlname != nil {
			finfo := tinfo.xmlname
			if finfo.name != "" && finfo.name != start.Name.Local {
				return UnmarshalError("expected element type <" + finfo.name + "> but have <" + start.Name.Local + ">")
			}
			if finfo.xmlns != "" && finfo.xmlns != start.Name.Space {
				e := "expected element <" + finfo.name + "> in name space " + finfo.xmlns + " but have "
				if start.Name.Space == "" {
					e += "no name space"
				} else {
					e += start.Name.Space
				}
				return UnmarshalError(e)
			}
			fv := finfo.value(sv, initNilPointers)
			if _, ok := fv.Interface().(Name); ok {
				fv.Set(reflect.ValueOf(start.Name))
			}
		}

		// 分配属性。
		for _, a := range start.Attr {
			handled := false
			any := -1
			for i := range tinfo.fields {
				finfo := &tinfo.fields[i]
				switch finfo.flags & fMode {
				case fAttr:
					strv := finfo.value(sv, initNilPointers)
					if a.Name.Local == finfo.name && (finfo.xmlns == "" || finfo.xmlns == a.Name.Space) {
						if err := d.unmarshalAttr(strv, a); err != nil {
							return err
						}
						handled = true
					}

				case fAny | fAttr:
					if any == -1 {
						any = i
					}
				}
			}
			if !handled && any >= 0 {
				finfo := &tinfo.fields[any]
				strv := finfo.value(sv, initNilPointers)
				if err := d.unmarshalAttr(strv, a); err != nil {
					return err
				}
			}
		}

		// 确定是否需要保存字符数据或注释。
		for i := range tinfo.fields {
			finfo := &tinfo.fields[i]
			switch finfo.flags & fMode {
			case fCDATA, fCharData:
				if !saveData.IsValid() {
					saveData = finfo.value(sv, initNilPointers)
				}

			case fComment:
				if !saveComment.IsValid() {
					saveComment = finfo.value(sv, initNilPointers)
				}

			case fAny, fAny | fElement:
				if !saveAny.IsValid() {
					saveAny = finfo.value(sv, initNilPointers)
				}

			case fInnerXML:
				if !saveXML.IsValid() {
					saveXML = finfo.value(sv, initNilPointers)
					if d.saved == nil {
						saveXMLIndex = 0
						d.saved = new(bytes.Buffer)
					} else {
						saveXMLIndex = d.savedOffset()
					}
				}
			}
		}
	}

	// 查找结束元素。
	// 一路上处理子元素。
Loop:
	for {
		var savedOffset int
		if saveXML.IsValid() {
			savedOffset = d.savedOffset()
		}
		tok, err := d.Token()
		if err != nil {
			return err
		}
		switch t := tok.(type) {
		case StartElement:
			consumed := false
			if sv.IsValid() {
				consumed, err = d.unmarshalPath(tinfo, sv, nil, &t)
				if err != nil {
					return err
				}
				if !consumed && saveAny.IsValid() {
					consumed = true
					if err := d.unmarshal(saveAny, &t); err != nil {
						return err
					}
				}
			}
			if !consumed {
				if err := d.Skip(); err != nil {
					return err
				}
			}

		case EndElement:
			if saveXML.IsValid() {
				saveXMLData = d.saved.Bytes()[saveXMLIndex:savedOffset]
				if saveXMLIndex == 0 {
					d.saved = nil
				}
			}
			break Loop

		case CharData:
			if saveData.IsValid() {
				data = append(data, t...)
			}

		case Comment:
			if saveComment.IsValid() {
				comment = append(comment, t...)
			}
		}
	}

	if saveData.IsValid() && saveData.CanInterface() && saveData.Type().Implements(textUnmarshalerType) {
		if err := saveData.Interface().(encoding.TextUnmarshaler).UnmarshalText(data); err != nil {
			return err
		}
		saveData = reflect.Value{}
	}

	if saveData.IsValid() && saveData.CanAddr() {
		pv := saveData.Addr()
		if pv.CanInterface() && pv.Type().Implements(textUnmarshalerType) {
			if err := pv.Interface().(encoding.TextUnmarshaler).UnmarshalText(data); err != nil {
				return err
			}
			saveData = reflect.Value{}
		}
	}

	if err := copyValue(saveData, data); err != nil {
		return err
	}

	switch t := saveComment; t.Kind() {
	case reflect.String:
		t.SetString(string(comment))
	case reflect.Slice:
		t.Set(reflect.ValueOf(comment))
	}

	switch t := saveXML; t.Kind() {
	case reflect.String:
		t.SetString(string(saveXMLData))
	case reflect.Slice:
		if t.Type().Elem().Kind() == reflect.Uint8 {
			t.Set(reflect.ValueOf(saveXMLData))
		}
	}

	return nil
}

func copyValue(dst reflect.Value, src []byte) (err error) {
	dst0 := dst

	if dst.Kind() == reflect.Pointer {
		if dst.IsNil() {
			dst.Set(reflect.New(dst.Type().Elem()))
		}
		dst = dst.Elem()
	}

	// 保存累积数据。
	switch dst.Kind() {
	case reflect.Invalid:
		// 可能是评论。
	default:
		return errors.New("cannot unmarshal into " + dst0.Type().String())
	case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
		if len(src) == 0 {
			dst.SetInt(0)
			return nil
		}
		itmp, err := strconv.ParseInt(strings.TrimSpace(string(src)), 10, dst.Type().Bits())
		if err != nil {
			return err
		}
		dst.SetInt(itmp)
	case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64, reflect.Uintptr:
		if len(src) == 0 {
			dst.SetUint(0)
			return nil
		}
		utmp, err := strconv.ParseUint(strings.TrimSpace(string(src)), 10, dst.Type().Bits())
		if err != nil {
			return err
		}
		dst.SetUint(utmp)
	case reflect.Float32, reflect.Float64:
		if len(src) == 0 {
			dst.SetFloat(0)
			return nil
		}
		ftmp, err := strconv.ParseFloat(strings.TrimSpace(string(src)), dst.Type().Bits())
		if err != nil {
			return err
		}
		dst.SetFloat(ftmp)
	case reflect.Bool:
		if len(src) == 0 {
			dst.SetBool(false)
			return nil
		}
		value, err := strconv.ParseBool(strings.TrimSpace(string(src)))
		if err != nil {
			return err
		}
		dst.SetBool(value)
	case reflect.String:
		dst.SetString(string(src))
	case reflect.Slice:
		if len(src) == 0 {
			// non nil to flag presence 
			src = []byte{}
		}
		dst.SetBytes(src)
	}
	return nil
}

// unmarshalPath沿着XML结构查找想要的
// 路径，并对其调用unmarshal。
// 消耗的结果告诉我们，在开始匹配结束元素之前，是否已经从解码器中消耗了XML元素
// 或者它是否是
// 因为开始对sv的字段不感兴趣，所以仍然未被触及。
func (d *Decoder) unmarshalPath(tinfo *typeInfo, sv reflect.Value, parents []string, start *StartElement) (consumed bool, err error) {
	recurse := false
Loop:
	for i := range tinfo.fields {
		finfo := &tinfo.fields[i]
		if finfo.flags&fElement == 0 || len(finfo.parents) < len(parents) || finfo.xmlns != "" && finfo.xmlns != start.Name.Space {
			continue
		}
		for j := range parents {
			if parents[j] != finfo.parents[j] {
				continue Loop
			}
		}
		if len(finfo.parents) == len(parents) && finfo.name == start.Name.Local {
			// 这是一对完美的组合，在球场上表现出色。
			return true, d.unmarshal(finfo.value(sv, initNilPointers), start)
		}
		if len(finfo.parents) > len(parents) && finfo.parents[len(parents)] == start.Name.Local {
			// 这是字段的前缀。中断并递归
			// 因为一个字段路径本身不能作为另一个字段路径的前缀。
			recurse = true

			// 我们可以重复使用同一个切片，只要我们
			// 不要尝试附加到它。
			parents = finfo.parents[:len(parents)+1]
			break
		}
	}
	if !recurse {
		// 我们与该元素没有业务往来。
		return false, nil
	}
	// 该元素对于任何字段都不是完美匹配的，但一个或多个字段将指向该元素的路径作为父
	// 前缀。递归并尝试匹配这些。
	for {
		var tok Token
		tok, err = d.Token()
		if err != nil {
			return true, err
		}
		switch t := tok.(type) {
		case StartElement:
			consumed2, err := d.unmarshalPath(tinfo, sv, parents, &t)
			if err != nil {
				return true, err
			}
			if !consumed2 {
				if err := d.Skip(); err != nil {
					return true, err
				}
			}
		case EndElement:
			return true, nil
		}
	}
}

// 跳过读取令牌，直到它已使用结束元素
// 匹配已使用的最新开始元素。
// 如果遇到start元素，它就会递归，因此可以用来跳过嵌套结构。
// 如果找到与起始
// 元素匹配的结束元素，则返回nil；否则，它将返回一个描述问题的错误。
func (d *Decoder) Skip() error {
	for {
		tok, err := d.Token()
		if err != nil {
			return err
		}
		switch tok.(type) {
		case StartElement:
			if err := d.Skip(); err != nil {
				return err
			}
		case EndElement:
			return nil
		}
	}
}
